---
title: 填充Excel
description: 填充Excel
---

## **簡單填充**

### 概述
基於模板文件，通過對象或 Map 填充數據到 Excel 中。

### 示例填充模板
![img](/images/docs/fill/simpleFill_file.png)
### 示例填充結果
![img](/images/docs/fill/simpleFill_result.png)
#### 示例對象
```java
@Getter
@Setter
@EqualsAndHashCode
public class FillData {
    private String name;
    private double number;
    private Date date;
}
```

#### 示例代碼
```java
@Test
public void simpleFill() {
    String templateFileName = "path/to/simple.xlsx";

    // 方案1：基於對象填充
    FillData fillData = new FillData();
    fillData.setName("張三");
    fillData.setNumber(5.2);
    FastExcel.write("simpleFill.xlsx")
        .withTemplate(templateFileName)
        .sheet()
        .doFill(fillData);

    // 方案2：基於 Map 填充
    Map<String, Object> map = new HashMap<>();
    map.put("name", "張三");
    map.put("number", 5.2);
    FastExcel.write("simpleFillMap.xlsx")
        .withTemplate(templateFileName)
        .sheet()
        .doFill(map);
}
```

---

## **填充列表**

### 概述
填充多個數據項到模板列表中，支持內存批量操作和文件緩存分批填充。

### 示例填充模板
![img](/images/docs/fill/listFill_file.png)
### 示例填充結果
![img](/images/docs/fill/listFill_result.png)

#### 示例代碼
```java
@Test
public void listFill() {
    String templateFileName = "path/to/list.xlsx";

    // 方案1：一次性填充所有數據
    FastExcel.write("listFill.xlsx")
        .withTemplate(templateFileName)
        .sheet()
        .doFill(data());

    // 方案2：分批填充
    try (ExcelWriter writer = FastExcel.write("listFillBatch.xlsx").withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = FastExcel.writerSheet().build();
        writer.fill(data(), writeSheet);
        writer.fill(data(), writeSheet);
    }
}
```

---

## **複雜的填充**

### 概述
在模板中填充多種數據類型，包括列表和普通變量。

### 示例填充模板
![img](/images/docs/fill/complexFill_file.png)
### 示例填充結果
![img](/images/docs/fill/complexFill_result.png)

#### 示例代碼
```java
@Test
public void complexFill() {
    String templateFileName = "path/to/complex.xlsx";

    try (ExcelWriter writer = FastExcel.write("complexFill.xlsx").withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = FastExcel.writerSheet().build();

        // 填充列表數據，開啟 forceNewRow
        FillConfig config = FillConfig.builder().forceNewRow(true).build();
        writer.fill(data(), config, writeSheet);

        // 填充普通變量
        Map<String, Object> map = new HashMap<>();
        map.put("date", "2024年11月20日");
        map.put("total", 1000);
        writer.fill(map, writeSheet);
    }
}
```

---

## **數據量大的複雜填充**

### 概述
優化大數據量填充性能，確保模板列表在最後一行，後續數據通過 `WriteTable` 填充。

### 示例填充模板
![img](/images/docs/fill/complexFillWithTable_file.png)
### 示例填充結果
![img](/images/docs/fill/complexFillWithTable_result.png)

#### 示例代碼
```java
@Test
public void complexFillWithTable() {
    String templateFileName = "path/to/complexFillWithTable.xlsx";

    try (ExcelWriter writer = FastExcel.write("complexFillWithTable.xlsx").withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = FastExcel.writerSheet().build();

        // 填充列表數據
        writer.fill(data(), writeSheet);

        // 填充其他變量
        Map<String, Object> map = new HashMap<>();
        map.put("date", "2024年11月20日");
        writer.fill(map, writeSheet);

        // 填充統計信息
        List<List<String>> totalList = new ArrayList<>();
        totalList.add(Arrays.asList(null, null, null, "統計: 1000"));
        writer.write(totalList, writeSheet);
    }
}
```

---

## **橫向填充**

### 概述
將列表數據橫向填充，適用於動態列數場景。

### 示例填充模板
![img](/images/docs/fill/horizontalFill_file.png)
### 示例填充結果
![img](/images/docs/fill/horizontalFill_result.png)

#### 示例代碼
```java
@Test
public void horizontalFill() {
    String templateFileName = "path/to/horizontal.xlsx";

    try (ExcelWriter writer = FastExcel.write("horizontalFill.xlsx").withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = FastExcel.writerSheet().build();

        FillConfig config = FillConfig.builder().direction(WriteDirectionEnum.HORIZONTAL).build();
        writer.fill(data(), config, writeSheet);

        Map<String, Object> map = new HashMap<>();
        map.put("date", "2024年11月20日");
        writer.fill(map, writeSheet);
    }
}
```

---

## **多列表組合填充**

### 概述
支持多個列表同時填充，列表之間通過前綴區分。

### 示例填充模板
![img](/images/docs/fill/compositeFill_file.png)
### 示例填充結果
![img](/images/docs/fill/compositeFill_result.png)

#### 示例代碼
```java
@Test
public void compositeFill() {
    String templateFileName = "path/to/composite.xlsx";

    try (ExcelWriter writer = FastExcel.write("compositeFill.xlsx").withTemplate(templateFileName).build()) {
        WriteSheet writeSheet = FastExcel.writerSheet().build();

        // 使用 FillWrapper 進行多列表填充
        writer.fill(new FillWrapper("data1", data()), writeSheet);
        writer.fill(new FillWrapper("data2", data()), writeSheet);
        writer.fill(new FillWrapper("data3", data()), writeSheet);

        Map<String, Object> map = new HashMap<>();
        map.put("date", new Date());
        writer.fill(map, writeSheet);
    }
}
```

---

## **填充使用場景總結**

| 功能               | 描述                                                                                      | 示例代码              |
|--------------------|-------------------------------------------------------------------------------------------|-----------------------|
| 最簡單的填充        | 通過對象或 Map 填充簡單數據                                                              | [simpleFill](#1)      |
| 填充列表           | 將列表數據填充到模板，支持分批填充                                                        | [listFill](#2)        |
| 複雜填充            | 在同一模板中填充多種數據類型，包括列表與普通變量                                           | [complexFill](#3)     |
| 大數據量複雜填充    | 優化大數據量填充性能，模板列表需放在最後一行                                               | [complexFillWithTable](#4) |
| 橫向填充            | 將列表數據橫向排列填充，適合動態列數據                                                    | [horizontalFill](#5)  |
| 多列表組合填充      | 支持多個列表同時填充，列表間通過前綴區分                                                   | [compositeFill](#6)   |
